test: close the false-green mechanisms, wire the dead CI gates (+ coverage gap analysis) - #436

What

An audit of what the test suite actually covers, plus the fixes for every gap it found in the "coverage the suite claims but does not have" category.

rake test:unit: 272 → 275 runs, 5723 → 6096 assertions, 0 failures. Assertions up 373 while the test count went down by 13. That ratio is the point — the suite got smaller and started checking more.

Doc: docs/20-29-testing-qa/20.10-test-coverage-gap-analysis-reference.md.

The audit

lib/ is healthy at 91.6% line coverage (716/782 relevant lines, SimpleCov over the pure-Ruby tests). The risk was never in the Ruby. It was in the layers the suite treats as rendered output, and in gates that reported green without testing anything.

Fixed

1. The integration suite skipped itself when the build failed

hugo_pipeline_test.rb called skip when the Hugo build failed — the asset pipeline is exactly what a broken build takes down, so the one regression these tests exist to catch reported 0 failures with all 11 tests skipped.

Now build_failure + flunk, separating "hugo not on PATH" from a real build error and printing the last 30 lines of build output. Verified by shimming hugo to /bin/false.

2. Two CI gates existed but ran nowhere

• rake test:html_proofer was invoked by no workflow, hook, or script. It now joins test:links in link-check.yml — as one rake invocation, because both default to the same OUTPUT_DIR and each triggers its own production build. build_for_linkcheck is memoized per process so the pair shares one build; two steps would build the site twice, the exact double-build that forced setup-hugo build: 'false' on this job.
• rake test:integration never gated a PR. Now its own Asset Pipeline job.

3. Two schema test files were 100% commented out

breadcrumb_schema_test.rb and service_schema_test.rb had zero active tests behind stale TODO: Restore when <X> schema implemented in reverted HTML markers. The build emits both today. Uncommented, 3 tests each.

A test file existing is not coverage — grep for def test_, not for the filename.

4. The lead-gen forms had no behavioral test

contact-form.html renders every field's name from [params.forms.contact]. Hugo renders a missing param as "" with no error, the page stays pixel-identical to the screenshot baseline, and leads submit blank.

New test/unit/lead_forms_test.rb. RED verified, not assumed — renaming first_name in hugo.toml:

contact-us/index.html: these fields render name="" and submit nothing.
Expected ["input_5_1"] to be empty.

5. FAQ structured data had no test

New faq_schema_test.rb (6 tests), including a sweep asserting every service page declaring faqs emits the schema — so a template guard that stops matching turns red instead of silently dropping rich results across the section.

6. Conditional-assertion guards — all 61 triaged

if el ... assert ... end passes when the element is absent. Every candidate was checked against the built page: element present → presence assertion; element absent → dead branch, deleted with an in-place note on what to assert if the feature ships.

This turned up four live bugs the guards were hiding:

1. single_template_test.rb never tested a single page. @test_pages led with "blog/index.html" and .first picked it, so 376 lines nominally covering single.html ran against the list page. Retargeting it to a real post immediately exposed bug 4.
2. Two item selectors omitted .blog-post — the only class the blog index renders. test_list_page_date_information and test_blog_post_partials matched zero items on every run since they were written.
3. css_urls.any? do |url| assert ... end — any? short-circuits on the first truthy block result and assert returns true, so only the first stylesheet was ever checked.
4. An over-strict a11y rule flagged image-only links as having no accessible name. A link wrapping an image takes its name from the image's alt (WCAG 2.1 SC 1.1.1). Fixed the rule, not the markup.

Skip-style guards were the same defect one level up and are gone too: list_template skipped 13 tests with no list page; 404_template skipped 12 with no 404.html; template_cleanup_validation had 9 next unless test_page_exists? + 3 return unless; seo_schema called skip "Schema N is empty - might indicate template issue" on exactly the template issue it exists to catch.

7. CI timeouts sized from the measured worst case

Running the new gates produced real numbers. Broken Internal Links: 3.5 min warm, 10.7 min cold (right after master moved and invalidated resources/_gen) — at its original 10-min cap that run would have gone red for nothing but cache state. Asset Pipeline: ~10 min for the suite, plus an actions/checkout measured at 7 min on one slow runner = 17 min against a 15-min cap.

Raised to 15 and 25. A gate that flakes on timeout teaches reviewers to ignore red, which costs more than the runner minutes.

Also

.okf/build/ci-gates.md claimed a toolchain drift test "fails the build when any copy diverges" — that test was deleted 2026-08-01, so the pins are convention-only with zero enforcement. Corrected, plus the same stale phrase in the Rakefile :guards comment.

Still open (documented, not in this PR)

Validator ratchet for blog/marketing content (course 0/82 em-dash files vs blog 208/607 — the rule holds exactly where a validator enforces it); DOM tests for the 4 page templates no test parses; static/sw.js; lib/sync/sources/sanity.rb (129 lines, referenced by nothing) delete-or-test; bin/qtest pages_for mapping.

Testing

• rake test:unit — 275 runs, 6096 assertions, 0 failures
• rake test:integration — 11 runs, 0 failures, and confirmed to fail loudly on a broken build
• rake test:guards — 5 runs, 0 failures
• CI green on the merged head: Unit Tests, build, Broken Internal Links, Asset Pipeline

Visual suites deliberately not run. The diff touches no themes/, layouts/, assets/, *.css, or content bodies — only test/, Rakefile, .github/workflows/, docs/, and .okf/. Per CLAUDE.md the bin/test + bin/dtest pair gates changes to visual surfaces; there are none here.

One environment note: parse_html_file uses bare File.read, so under a US-ASCII default encoding (no LANG) Nokogiri aborts and 73 template tests fail for a non-template reason. Run under LANG=C.UTF-8.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fza9okyuQ5QdXesVQ85n3b